---
title: "Integrate Mastra in your Express project | Frameworks"
description: A step-by-step guide to integrating Mastra with an Express backend.
---

# Integrate Mastra in your Express project

Mastra integrates with Express, making it easy to:

- Build flexible APIs to serve AI-powered features
- Maintain full control over your server logic and routing
- Scale your backend independently of your frontend

Express can invoke Mastra directly so you don't need to run a Mastra server alongside your Express server.

In this guide you'll learn how to install the necessary Mastra dependencies, create an example agent, and invoke Mastra from an Express API route.

## Prerequisites

- An existing Express app set up with TypeScript
- Node.js `v22.13.0` or later
- An API key from a supported [Model Provider](/models/v1)

## Adding Mastra

First, install the necessary Mastra dependencies to run an Agent. This guide uses OpenAI as its model but you can use any supported [model provider](/models/v1).

```bash copy
npm install mastra@beta @mastra/core@beta @mastra/libsql@beta zod@^3.0.0
```

If not existent yet, create an `.env` file and add your OpenAI API key:

```bash title=".env" copy
OPENAI_API_KEY=<your-api-key>
```

:::note

Each LLM provider uses a different env var. See [Model Providers](/models/v1/providers/) for more information.

:::

Create a Mastra configuration file at `src/mastra/index.ts`:

```ts title="src/mastra/index.ts" copy
import { Mastra } from "@mastra/core";

export const mastra = new Mastra({});
```

Create a `weatherTool` that the `weatherAgent` will use at `src/mastra/tools/weather-tool.ts`. It returns a placeholder value inside the `execute()` function (you'd put your API calls in here).

```ts title="src/mastra/tools/weather-tool.ts" copy
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    output: z.string(),
  }),
  execute: async () => {
    return {
      output: "The weather is sunny",
    };
  },
});
```

Add a `weatherAgent` at `src/mastra/agents/weather-agent.ts`:

```ts title="src/mastra/agents/weather-agent.ts" copy
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn't in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  model: "openai/gpt-5.1",
  tools: { weatherTool },
});
```

Lastly, add the `weatherAgent` to `src/mastra/index.ts`:

```ts title="src/mastra/index.ts" copy {2, 5}
import { Mastra } from "@mastra/core";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
});
```

Now you're done with setting up the Mastra boilerplate code and are ready to integrate it into your Express routes.

## Using Mastra with Express

Create an `/api/weather` endpoint that expects a `city` query parameter. The `city` parameter will be passed to the `weatherAgent` when asking it through a prompt.

You might have a file like this in your existing project:

```ts title="src/server.ts" copy
import express, { Request, Response } from "express";

const app = express();
const port = 3456;

app.get("/", (req: Request, res: Response) => {
  res.send("Hello, world!");
});

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});
```

Adding the `/api/weather` endpoint looks like this:

```ts title="src/server.ts" copy {2, 11-27}
import express, { Request, Response } from "express";
import { mastra } from "./mastra";

const app = express();
const port = 3456;

app.get("/", (req: Request, res: Response) => {
  res.send("Hello, world!");
});

app.get("/api/weather", async (req: Request, res: Response) => {
  const { city } = req.query as { city?: string };

  if (!city) {
    return res.status(400).send("Missing 'city' query parameter");
  }

  const agent = mastra.getAgent("weatherAgent");

  try {
    const result = await agent.generate(`What's the weather like in ${city}?`);
    res.send(result.text);
  } catch (error) {
    console.error("Agent error:", error);
    res.status(500).send("An error occurred while processing your request");
  }
});

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});
```

By importing the `src/mastra/index.ts` file you can use methods like [`.getAgent()`](/reference/v1/core/getAgent) to get programmatic access. With [`.generate()`](/reference/v1/agents/generate) you then can interact with the respective agent.

:::note

Read the [Agent reference docs](/reference/v1/agents/agent) to learn more.

:::

Start your Express server and visit the `/api/weather` endpoint. For example:

```
http://localhost:3456/api/weather?city=London
```

You should get a response back similar to this:

```
The weather in London is currently sunny. If you need more details like humidity, wind conditions, or precipitation, just let me know!
```

## Running the Agent Server

In production it's not necessary to run Mastra alongside your Express server. But for development Mastra offers a [Local Development Environment](/docs/v1/getting-started/studio) which you can use to improve and debug your agent.

Add a script to your `package.json`:

```json title="package.json" copy
{
  "scripts": {
    "mastra:dev": "mastra dev"
  }
}
```

Start the Mastra dev server:

```bash copy
npm run mastra:dev
```
